Cream of the Crop 26

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 26 / Cream of the Crop 26.iso / os2 / octa209b.zip / octave-2.09 / doc / octave.i07 (.txt) < prev next >

Wrap

GNU Info File | 1997-08-20 | 50KB | 1,104 lines

This is Info file octave, produced by Makeinfo-1.64 from the input file octave.tex. START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright (C) 1996, 1997 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. File: octave, Node: Rearranging Matrices, Next: Special Utility Matrices, Prev: Finding Elements and Checking Conditions, Up: Matrix Manipulation Rearranging Matrices ==================== - Function File: fliplr (X) Return a copy of X with the order of the columns reversed. For example, fliplr ([1, 2; 3, 4]) => 2 1 4 3 - Function File: flipud (X) Return a copy of X with the order of the rows reversed. For example, flipud ([1, 2; 3, 4]) => 3 4 1 2 - Function File: rot90 (X, N) Return a copy of X with the elements rotated counterclockwise in 90-degree increments. The second argument is optional, and specifies how many 90-degree rotations are to be applied (the default value is 1). Negative values of N rotate the matrix in a clockwise direction. For example, rot90 ([1, 2; 3, 4], -1) => 3 1 4 2 rotates the given matrix clockwise by 90 degrees. The following are all equivalent statements: rot90 ([1, 2; 3, 4], -1) == rot90 ([1, 2; 3, 4], 3) == rot90 ([1, 2; 3, 4], 7) - Function File: reshape (A, M, N) Return a matrix with M rows and N columns whose elements are taken from the matrix A. To decide how to order the elements, Octave pretends that the elements of a matrix are stored in column-major order (like Fortran arrays are stored). For example, reshape ([1, 2, 3, 4], 2, 2) => 1 3 2 4 If the variable `do_fortran_indexing' is nonzero, the `reshape' function is equivalent to retval = zeros (m, n); retval (:) = a; but it is somewhat less cryptic to use `reshape' instead of the colon operator. Note that the total number of elements in the original matrix must match the total number of elements in the new matrix. - Function File: shift (X, B) If X is a vector, perform a circular shift of length B of the elements of X. If X is a matrix, do the same for each column of X. - Loadable Function: [S, I] = sort (X) Return a copy of X with the elements elements arranged in increasing order. For matrices, `sort' orders the elements in each column. For example, sort ([1, 2; 2, 3; 3, 1]) => 1 1 2 2 3 3 The `sort' function may also be used to produce a matrix containing the original row indices of the elements in the sorted matrix. For example, [s, i] = sort ([1, 2; 2, 3; 3, 1]) => s = 1 1 2 2 3 3 => i = 1 3 2 1 3 2 Since the `sort' function does not allow sort keys to be specified, it can't be used to order the rows of a matrix according to the values of the elements in various columns(1) in a single call. Using the second output, however, it is possible to sort all rows based on the values in a given column. Here's an example that sorts the rows of a matrix based on the values in the second column. a = [1, 2; 2, 3; 3, 1]; [s, i] = sort (a (:, 2)); a (i, :) => 3 1 1 2 2 3 - Function File: tril (A, K) - Function File: triu (A, K) Return a new matrix formed by extracting extract the lower (`tril') or upper (`triu') triangular part of the matrix A, and setting all other elements to zero. The second argument is optional, and specifies how many diagonals above or below the main diagonal should also be set to zero. The default value of K is zero, so that `triu' and `tril' normally include the main diagonal as part of the result matrix. If the value of K is negative, additional elements above (for `tril') or below (for `triu') the main diagonal are also selected. The absolute value of K must not be greater than the number of sub- or super-diagonals. For example, tril (ones (3), -1) => 0 0 0 1 0 0 1 1 0 and tril (ones (3), 1) => 1 1 0 1 1 1 1 1 1 - Function File: vec (X) Return the vector obtained by stacking the columns of the matrix X one above the other. - Function File: vech (X) Return the vector obtained by eliminating all supradiagonal elements of the square matrix X and stacking the result one column above the other. ---------- Footnotes ---------- (1) For example, to first sort based on the values in column 1, and then, for any values that are repeated in column 1, sort based on the values found in column 2, etc. File: octave, Node: Special Utility Matrices, Next: Famous Matrices, Prev: Rearranging Matrices, Up: Matrix Manipulation Special Utility Matrices ======================== - Built-in Function: eye (X) - Built-in Function: eye (N, M) Return an identity matrix. If invoked with a single scalar argument, `eye' returns a square matrix with the dimension specified. If you supply two scalar arguments, `eye' takes them to be the number of rows and columns. If given a vector with two elements, `eye' uses the values of the elements as the number of rows and columns, respectively. For example, eye (3) => 1 0 0 0 1 0 0 0 1 The following expressions all produce the same result: eye (2) == eye (2, 2) == eye (size ([1, 2; 3, 4]) For compatibility with MATLAB, calling `eye' with no arguments is equivalent to calling it with an argument of 1. - Built-in Function: ones (X) - Built-in Function: ones (N, M) Return a matrix whose elements are all 1. The arguments are handled the same as the arguments for `eye'. If you need to create a matrix whose values are all the same, you should use an expression like val_matrix = val * ones (n, m) - Built-in Function: zeros (X) - Built-in Function: zeros (N, M) Return a matrix whose elements are all 0. The arguments are handled the same as the arguments for `eye'. - Loadable Function: rand (X) - Loadable Function: rand (N, M) - Loadable Function: rand (`"seed"', X) Return a matrix with random elements uniformly distributed on the interval (0, 1). The arguments are handled the same as the arguments for `eye'. In addition, you can set the seed for the random number generator using the form rand ("seed", X) where X is a scalar value. If called as rand ("seed") `rand' returns the current value of the seed. - Loadable Function: randn (X) - Loadable Function: randn (N, M) - Loadable Function: randn (`"seed"', X) Return a matrix with normally distributed random elements. The arguments are handled the same as the arguments for `eye'. In addition, you can set the seed for the random number generator using the form randn ("seed", X) where X is a scalar value. If called as randn ("seed") `randn' returns the current value of the seed. The `rand' and `randn' functions use separate generators. This ensures that rand ("seed", 13); randn ("seed", 13); u = rand (100, 1); n = randn (100, 1); rand ("seed", 13); randn ("seed", 13); u = zeros (100, 1); n = zeros (100, 1); for i = 1:100 u(i) = rand (); n(i) = randn (); end produce equivalent results. Normally, `rand' and `randn' obtain their initial seeds from the system clock, so that the sequence of random numbers is not the same each time you run Octave. If you really do need for to reproduce a sequence of numbers exactly, you can set the seed to a specific value. If it is invoked without arguments, `rand' and `randn' return a single element of a random sequence. The `rand' and `randn' functions use Fortran code from RANLIB, a library of fortran routines for random number generation, compiled by Barry W. Brown and James Lovato of the Department of Biomathematics at The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030. - Built-in Function: diag (V, K) Return a diagonal matrix with vector V on diagonal K. The second argument is optional. If it is positive, the vector is placed on the K-th super-diagonal. If it is negative, it is placed on the -K-th sub-diagonal. The default value of K is 0, and the vector is placed on the main diagonal. For example, diag ([1, 2, 3], 1) => 0 1 0 0 0 0 2 0 0 0 0 3 0 0 0 0 The functions `linspace' and `logspace' make it very easy to create vectors with evenly or logarithmically spaced elements. *Note Ranges::. - Function File: linspace (BASE, LIMIT, N) Return a row vector with N linearly spaced elements between BASE and LIMIT. The number of elements, N, must be greater than 1. The BASE and LIMIT are always included in the range. If BASE is greater than LIMIT, the elements are stored in decreasing order. If the number of points is not specified, a value of 100 is used. The `linspace' function always returns a row vector, regardless of the value of `prefer_column_vectors'. - Function File: logspace (BASE, LIMIT, N) Similar to `linspace' except that the values are logarithmically spaced from 10^base to 10^limit. If LIMIT is equal to pi, the points are between 10^base and pi, *not* 10^base and 10^pi, in order to be compatible with the corresponding MATLAB function. - Built-in Variable: treat_neg_dim_as_zero If the value of `treat_neg_dim_as_zero' is nonzero, expressions like eye (-1) produce an empty matrix (i.e., row and column dimensions are zero). Otherwise, an error message is printed and control is returned to the top level. The default value is 0. File: octave, Node: Famous Matrices, Prev: Special Utility Matrices, Up: Matrix Manipulation Famous Matrices =============== The following functions return famous matrix forms. - Function File: hadamard (K) Return the Hadamard matrix of order n = 2^k. - Function File: hankel (C, R) Return the Hankel matrix constructed given the first column C, and (optionally) the last row R. If the last element of C is not the same as the first element of R, the last element of C is used. If the second argument is omitted, the last row is taken to be the same as the first column. A Hankel matrix formed from an m-vector C, and an n-vector R, has the elements H (i, j) = c (i+j-1), i+j-1 <= m; H (i, j) = r (i+j-m), otherwise - Function File: hilb (N) Return the Hilbert matrix of order N. The i, j element of a Hilbert matrix is defined as H (i, j) = 1 / (i + j - 1) - Function File: invhilb (N) Return the inverse of a Hilbert matrix of order N. This is exact. Compare with the numerical calculation of `inverse (hilb (n))', which suffers from the ill-conditioning of the Hilbert matrix, and the finite precision of your computer's floating point arithmetic. - Function File: toeplitz (C, R) Return the Toeplitz matrix constructed given the first column C, and (optionally) the first row R. If the first element of C is not the same as the first element of R, the first element of C is used. If the second argument is omitted, the first row is taken to be the same as the first column. A square Toeplitz matrix has the form c(0) r(1) r(2) ... r(n) c(1) c(0) r(1) r(n-1) c(2) c(1) c(0) r(n-2) . . . . . . c(n) c(n-1) c(n-2) ... c(0) - Function File: vander (C) Return the Vandermonde matrix whose next to last column is C. A Vandermonde matrix has the form c(0)^n ... c(0)^2 c(0) 1 c(1)^n ... c(1)^2 c(1) 1 . . . . . . . . . . . . c(n)^n ... c(n)^2 c(n) 1 File: octave, Node: Arithmetic, Next: Linear Algebra, Prev: Matrix Manipulation, Up: Top Arithmetic ********** Unless otherwise noted, all of the functions described in this chapter will work for real and complex scalar or matrix arguments. * Menu: * Utility Functions:: * Complex Arithmetic:: * Trigonometry:: * Sums and Products:: * Special Functions:: * Mathematical Constants:: File: octave, Node: Utility Functions, Next: Complex Arithmetic, Prev: Arithmetic, Up: Arithmetic Utility Functions ================= The following functions are available for working with complex numbers. Each expects a single argument. They are called "mapping functions" because when given a matrix argument, they apply the given function to each element of the matrix. - Mapping Function: ceil (X) Return the smallest integer not less than X. If X is complex, return `ceil (real (X)) + ceil (imag (X)) * I'. - Mapping Function: exp (X) Compute the exponential of X. To compute the matrix exponential, see *Note Linear Algebra::. - Mapping Function: fix (X) Truncate X toward zero. If X is complex, return `fix (real (X)) + fix (imag (X)) * I'. - Mapping Function: floor (X) Return the largest integer not greater than X. If X is complex, return `floor (real (X)) + floor (imag (X)) * I'. - Mapping Function: gcd (X, `...') Compute the greatest common divisor of the elements of X, or the list of all the arguments. For example, gcd (a1, ..., ak) is the same as gcd ([a1, ..., ak]) An optional second return value, V contains an integer vector such that g = v(1) * a(k) + ... + v(k) * a(k) - Mapping Function: lcm (X, `...') Compute the least common multiple of the elements elements of X, or the list of all the arguments. For example, lcm (a1, ..., ak) is the same as lcm ([a1, ..., ak]). - Mapping Function: log (X) Compute the natural logarithm of X. To compute the matrix logarithm, see *Note Linear Algebra::. - Mapping Function: log10 (X) Compute the base-10 logarithm of X. - Mapping Function: Y = log2 (X) - Mapping Function: [F, E] log2 (X) Compute the base-2 logarithm of X. With two outputs, returns F and E such that 1/2 <= abs(f) < 1 and x = f * 2^e. - Loadable Function: max (X) For a vector argument, return the maximum value. For a matrix argument, return the maximum value from each column, as a row vector. Thus, max (max (X)) returns the largest element of X. For complex arguments, the magnitude of the elements are used for comparison. - Loadable Function: min (X) Like `max', but return the minimum value. - Function File: nextpow2 (X) If X is a scalar, returns the first integer N such that 2^n >= abs (x). If X is a vector, return `nextpow2 (length (X))'. - Mapping Function: pow2 (X) - Mapping Function: pow2 (F, E) With one argument, computes 2 .^ x for each element of X. With two arguments, returns f .* (2 .^ e). - Mapping Function: rem (X, Y) Return the remainder of `X / Y', computed using the expression x - y .* fix (x ./ y) An error message is printed if the dimensions of the arguments do not agree, or if either of the arguments is complex. - Mapping Function: round (X) Return the integer nearest to X. If X is complex, return `round (real (X)) + round (imag (X)) * I'. - Mapping Function: sign (X) Compute the "signum" function, which is defined as -1, x < 0; sign (x) = 0, x = 0; 1, x > 0. For complex arguments, `sign' returns `x ./ abs (X)'. - Mapping Function: sqrt (X) Compute the square root of X. If X is negative, a complex result is returned. To compute the matrix square root, see *Note Linear Algebra::. - Mapping Function: xor (X, Y) Return the `exclusive or' of the entries of X and Y. For boolean expressions X and Y, `xor (X, Y)' is true if and only if X or Y is true, but not if both X and Y are true. File: octave, Node: Complex Arithmetic, Next: Trigonometry, Prev: Utility Functions, Up: Arithmetic Complex Arithmetic ================== The following functions are available for working with complex numbers. Each expects a single argument. Given a matrix they work on an element by element basis. In the descriptions of the following functions, Z is the complex number X + IY, where I is defined as `sqrt (-1)'. - Mapping Function: abs (Z) Compute the magnitude of Z, defined as |Z| = `sqrt (x^2 + y^2)'. For example, abs (3 + 4i) => 5 - Mapping Function: arg (Z) - Mapping Function: angle (Z) Compute the argument of Z, defined as THETA = `atan (Y/X)'. in radians. For example, arg (3 + 4i) => 0.92730 - Mapping Function: conj (Z) Return the complex conjugate of Z, defined as `conj (Z)' = X - IY. - Mapping Function: imag (Z) Return the imaginary part of Z as a real number. - Mapping Function: real (Z) Return the real part of Z. File: octave, Node: Trigonometry, Next: Sums and Products, Prev: Complex Arithmetic, Up: Arithmetic Trigonometry ============ Octave provides the following trigonometric functions: - Mapping Function: sin (Z) - Mapping Function: cos (Z) - Mapping Function: tan (Z) - Mapping Function: sec (Z) - Mapping Function: csc (Z) - Mapping Function: cot (Z) The ordinary trigonometric functions. - Mapping Function: asin (Z) - Mapping Function: acos (Z) - Mapping Function: atan (Z) - Mapping Function: asec (Z) - Mapping Function: acsc (Z) - Mapping Function: acot (Z) The ordinary inverse trigonometric functions. - Mapping Function: sinh (Z) - Mapping Function: cosh (Z) - Mapping Function: tanh (Z) - Mapping Function: sech (Z) - Mapping Function: csch (Z) - Mapping Function: coth (Z) Hyperbolic trigonometric functions. - Mapping Function: asinh (Z) - Mapping Function: acosh (Z) - Mapping Function: atanh (Z) - Mapping Function: asech (Z) - Mapping Function: acsch (Z) - Mapping Function: acoth (Z) Inverse hyperbolic trigonometric functions. Each of these functions expect a single argument. For matrix arguments, they work on an element by element basis. For example, sin ([1, 2; 3, 4]) => 0.84147 0.90930 0.14112 -0.75680 - Mapping Function: atan2 (Y, X) Return the arctangent of Y/X. The signs of the arguments are used to determine the quadrant of the result, which is in the range `pi' to -`pi'. File: octave, Node: Sums and Products, Next: Special Functions, Prev: Trigonometry, Up: Arithmetic Sums and Products ================= - Built-in Function: sum (X) For a vector argument, return the sum of all the elements. For a matrix argument, return the sum of the elements in each column, as a row vector. The sum of an empty matrix is 0 if it has no columns, or a vector of zeros if it has no rows (*note Empty Matrices::.). - Built-in Function: prod (X) For a vector argument, return the product of all the elements. For a matrix argument, return the product of the elements in each column, as a row vector. The product of an empty matrix is 1 if it has no columns, or a vector of ones if it has no rows (*note Empty Matrices::.). - Built-in Function: cumsum (X) Return the cumulative sum of each column of X. For example, cumsum ([1, 2; 3, 4]) => 1 2 4 6 - Built-in Function: cumprod (X) Return the cumulative product of each column of X. For example, cumprod ([1, 2; 3, 4]) => 1 2 3 8 - Built-in Function: sumsq (X) For a vector argument, return the sum of the squares of all the elements. For a matrix argument, return the sum of the squares of the elements in each column, as a row vector. File: octave, Node: Special Functions, Next: Mathematical Constants, Prev: Sums and Products, Up: Arithmetic Special Functions ================= - Mapping Function: beta (A, B) Return the Beta function, beta (a, b) = gamma (a) * gamma (b) / gamma (a + b). - Mapping Function: betai (A, B, X) Return the incomplete Beta function, x / betai (a, b, x) = beta (a, b)^(-1) | t^(a-1) (1-t)^(b-1) dt. / t=0 If x has more than one component, both A and B must be scalars. If X is a scalar, A and B must be of compatible dimensions. - Mapping Function: bincoeff (N, K) Return the binomial coefficient of N and K, defined as / \ | n | n (n-1) (n-2) ... (n-k+1) | | = ------------------------- | k | k! \ / For example, bincoeff (5, 2) => 10 - Mapping Function: erf (Z) Computes the error function, z / erf (z) = (2/sqrt (pi)) | e^(-t^2) dt / t=0 - Mapping Function: erfc (Z) Computes the complementary error function, `1 - erf (Z)'. - Mapping Function: erfinv (Z) Computes the inverse of the error function, - Mapping Function: gamma (Z) Computes the Gamma function, infinity / gamma (z) = | t^(z-1) exp (-t) dt. / t=0 - Mapping Function: gammai (A, X) Computes the incomplete gamma function, x 1 / gammai (a, x) = --------- | exp (-t) t^(a-1) dt gamma (a) / t=0 If A is scalar, then `gammai (A, X)' is returned for each element of X and vice versa. If neither A nor X is scalar, the sizes of A and X must agree, and GAMMAI is applied element-by-element. - Mapping Function: lgamma (A, X) - Mapping Function: gammaln (A, X) Return the natural logarithm of the gamma function. - Function File: cross (X, Y) Computes the vector cross product of the two 3-dimensional vectors X and Y. For example, cross ([1,1,0], [0,1,1]) => [ 1; -1; 1 ] - Function File: commutation_matrix (M, N) Return the commutation matrix K(m,n) which is the unique M*N by M*N matrix such that K(M,N) * vec (A) = vec (A') for all M by N matrices A. If only one argument M is given, K(m,m) is returned. See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics. - Function File: duplication_matrix (N) Return the duplication matrix D_N which is the unique N^2 by N*(N+1)/2 matrix such that D_N \cdot vech (A) = vec (A) for all symmetric N by N matrices A. See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics. File: octave, Node: Mathematical Constants, Prev: Special Functions, Up: Arithmetic Mathematical Constants ====================== - Built-in Variable: I - Built-in Variable: J - Built-in Variable: i - Built-in Variable: j A pure imaginary number, defined as `sqrt (-1)'. The `I' and `J' forms are true constants, and cannot be modified. The `i' and `j' forms are like ordinary variables, and may be used for other purposes. However, unlike other variables, they once again assume their special predefined values if they are cleared *Note Status of Variables::. - Built-in Variable: Inf - Built-in Variable: inf Infinity. This is the result of an operation like 1/0, or an operation that results in a floating point overflow. - Built-in Variable: NaN - Built-in Variable: nan Not a number. This is the result of an operation like 0/0, or `Inf - Inf', or any operation with a NaN. - Built-in Variable: pi The ratio of the circumference of a circle to its diameter. Internally, `pi' is computed as `4.0 * atan (1.0)'. - Built-in Variable: e The base of natural logarithms. The constant E satisfies the equation `log' (E) = 1. - Built-in Variable: eps The machine precision. More precisely, `eps' is the largest relative spacing between any two adjacent numbers in the machine's floating point system. This number is obviously system-dependent. On machines that support 64 bit IEEE floating point arithmetic, `eps' is approximately 2.2204e-16. - Built-in Variable: realmax The largest floating point number that is representable. The actual value is system-dependent. On machines that support 64 bit IEEE floating point arithmetic, `realmax' is approximately 1.7977e+308 - Built-in Variable: realmin The smallest floating point number that is representable. The actual value is system-dependent. On machines that support 64 bit IEEE floating point arithmetic, `realmin' is approximately 2.2251e-308 File: octave, Node: Linear Algebra, Next: Nonlinear Equations, Prev: Arithmetic, Up: Top Linear Algebra ************** This chapter documents the linear algebra functions of Octave. Reference material for many of these functions may be found in Golub and Van Loan, `Matrix Computations, 2nd Ed.', Johns Hopkins, 1989, and in `LAPACK Users' Guide', SIAM, 1992. * Menu: * Basic Matrix Functions:: * Matrix Factorizations:: * Functions of a Matrix:: File: octave, Node: Basic Matrix Functions, Next: Matrix Factorizations, Prev: Linear Algebra, Up: Linear Algebra Basic Matrix Functions ====================== - Loadable Function: AA = balance (A, OPT) - Loadable Function: [DD, AA] = balance (A, OPT) - Loadable Function: [CC, DD, AA, BB] = balance (A, B, OPT) `[dd, aa] = balance (a)' returns `aa = dd \ a * dd'. `aa' is a matrix whose row and column norms are roughly equal in magnitude, and `dd' = `p * d', where `p' is a permutation matrix and `d' is a diagonal matrix of powers of two. This allows the equilibration to be computed without roundoff. Results of eigenvalue calculation are typically improved by balancing first. `[cc, dd, aa, bb] = balance (a, b)' returns `aa = cc*a*dd' and `bb = cc*b*dd)', where `aa' and `bb' have non-zero elements of approximately the same magnitude and `cc' and `dd' are permuted diagonal matrices as in `dd' for the algebraic eigenvalue problem. The eigenvalue balancing option `opt' is selected as follows: `"N"', `"n"' No balancing; arguments copied, transformation(s) set to identity. `"P"', `"p"' Permute argument(s) to isolate eigenvalues where possible. `"S"', `"s"' Scale to improve accuracy of computed eigenvalues. `"B"', `"b"' Permute and scale, in that order. Rows/columns of a (and b) that are isolated by permutation are not scaled. This is the default behavior. Algebraic eigenvalue balancing uses standard LAPACK routines. Generalized eigenvalue problem balancing uses Ward's algorithm (SIAM Journal on Scientific and Statistical Computing, 1981). - : cond (A) Compute the (two-norm) condition number of a matrix. `cond (a)' is defined as `norm (a) * norm (inv (a))', and is computed via a singular value decomposition. - Loadable Function: det (A) Compute the determinant of A using LINPACK. - Loadable Function: LAMBDA = eig (A) - Loadable Function: [V, LAMBDA] = eig (A) The eigenvalues (and eigenvectors) of a matrix are computed in a several step process which begins with a Hessenberg decomposition, followed by a Schur decomposition, from which the eigenvalues are apparent. The eigenvectors, when desired, are computed by further manipulations of the Schur decomposition. - Loadable Function: G = givens (X, Y) - Loadable Function: [C, S] = givens (X, Y) Return a 2 by 2 orthogonal matrix `G = [C S; -S' C]' such that `G [X; Y] = [*; 0]' with X and Y scalars. For example, givens (1, 1) => 0.70711 0.70711 -0.70711 0.70711 - Loadable Function: inv (A) - Loadable Function: inverse (A) Compute the inverse of the square matrix A. - Function File: norm (A, P) Compute the p-norm of the matrix A. If the second argument is missing, `p = 2' is assumed. If A is a matrix: P = `1' 1-norm, the largest column sum of A. P = `2' Largest singular value of A. P = `Inf' Infinity norm, the largest row sum of A. P = `"fro"' Frobenius norm of A, `sqrt (sum (diag (A' * A)))'. If A is a vector or a scalar: P = `Inf' `max (abs (A))'. P = `-Inf' `min (abs (A))'. other p-norm of A, `(sum (abs (A) .^ P)) ^ (1/P)'. - Function File: null (A, TOL) Return an orthonormal basis of the null space of A. The dimension of the null space is taken as the number of singular values of A not greater than TOL. If the argument TOL is missing, it is computed as max (size (A)) * max (svd (A)) * eps - Function File: orth (A, TOL) Return an orthonormal basis of the range space of A. The dimension of the range space is taken as the number of singular values of A greater than TOL. If the argument TOL is missing, it is computed as max (size (A)) * max (svd (A)) * eps - Function File: pinv (X, TOL) Return the pseudoinverse of X. Singular values less than TOL are ignored. If the second argument is omitted, it is assumed that tol = max (size (X)) * sigma_max (X) * eps, where `sigma_max (X)' is the maximal singular value of X. - Function File: rank (A, TOL) Compute the rank of A, using the singular value decomposition. The rank is taken to be the number of singular values of A that are greater than the specified tolerance TOL. If the second argument is omitted, it is taken to be tol = max (size (A)) * sigma (1) * eps; where `eps' is machine precision and `sigma' is the largest singular value of A. - Function File: trace (A) Compute the trace of A, `sum (diag (A))'. File: octave, Node: Matrix Factorizations, Next: Functions of a Matrix, Prev: Basic Matrix Functions, Up: Linear Algebra Matrix Factorizations ===================== - Loadable Function: chol (A) Compute the Cholesky factor, R, of the symmetric positive definite matrix A, where r' * r = a. - Loadable Function: H = hess (A) - Loadable Function: [P, H] = hess (A) Compute the Hessenberg decomposition of the matrix A. The Hessenberg decomposition is usually used as the first step in an eigenvalue computation, but has other applications as well (see Golub, Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979. The Hessenberg decomposition is `p * h * p' = a' where `p' is a square unitary matrix (`p' * p = I', using complex-conjugate transposition) and `h' is upper Hessenberg (`i >= j+1 => h (i, j) = 0'). - Loadable Function: [L, U, P] = lu (A) Compute the LU decomposition of A, using subroutines from LAPACK. The result is returned in a permuted form, according to the optional return value P. For example, given the matrix `a = [1, 2; 3, 4]', [l, u, p] = lu (a) returns l = 1.00000 0.00000 0.33333 1.00000 u = 3.00000 4.00000 0.00000 0.66667 p = 0 1 1 0 - Loadable Function: [Q, R, P] = qr (A) Compute the QR factorization of A, using standard LAPACK subroutines. For example, given the matrix `a = [1, 2; 3, 4]', [q, r] = qr (a) returns q = -0.31623 -0.94868 -0.94868 0.31623 r = -3.16228 -4.42719 0.00000 -0.63246 The `qr' factorization has applications in the solution of least squares problems `min norm(A x - b)' for overdetermined systems of equations (i.e., `a' is a tall, thin matrix). The QR factorization is `q * r = a' where `q' is an orthogonal matrix and `r' is upper triangular. The permuted QR factorization `[Q, R, P] = qr (A)' forms the QR factorization such that the diagonal entries of `r' are decreasing in magnitude order. For example, given the matrix `a = [1, 2; 3, 4]', [q, r, pi] = qr(a) returns q = -0.44721 -0.89443 -0.89443 0.44721 r = -4.47214 -3.13050 0.00000 0.44721 p = 0 1 1 0 The permuted `qr' factorization `[q, r, p] = qr (a)' factorization allows the construction of an orthogonal basis of `span (a)'. - Loadable Function: S = schur (A) - Loadable Function: [U, S] = schur (A, OPT) The Schur decomposition is used to compute eigenvalues of a square matrix, and has applications in the solution of algebraic Riccati equations in control (see `are' and `dare'). `schur' always returns `s = u' * a * u' where `u' is a unitary matrix (`u'* u' is identity) and `s' is upper triangular. The eigenvalues of `a' (and `s') are the diagonal elements of `s' If the matrix `a' is real, then the real Schur decomposition is computed, in which the matrix `u' is orthogonal and `s' is block upper triangular with blocks of size at most `2 x 2' blocks along the diagonal. The diagonal elements of `s' (or the eigenvalues of the `2 x 2' blocks, when appropriate) are the eigenvalues of `a' and `s'. The eigenvalues are optionally ordered along the diagonal according to the value of `opt'. `opt = "a"' indicates that all eigenvalues with negative real parts should be moved to the leading block of `s' (used in `are'), `opt = "d"' indicates that all eigenvalues with magnitude less than one should be moved to the leading block of `s' (used in `dare'), and `opt = "u"', the default, indicates that no ordering of eigenvalues should occur. The leading `k' columns of `u' always span the `a'-invariant subspace corresponding to the `k' leading eigenvalues of `s'. - Loadable Function: S = svd (A) - Loadable Function: [U, S, V] = svd (A) Compute the singular value decomposition of A a = u * sigma * v' The function `svd' normally returns the vector of singular values. If asked for three return values, it computes U, S, and V. For example, svd (hilb (3)) returns ans = 1.4083189 0.1223271 0.0026873 and [u, s, v] = svd (hilb (3)) returns u = -0.82704 0.54745 0.12766 -0.45986 -0.52829 -0.71375 -0.32330 -0.64901 0.68867 s = 1.40832 0.00000 0.00000 0.00000 0.12233 0.00000 0.00000 0.00000 0.00269 v = -0.82704 0.54745 0.12766 -0.45986 -0.52829 -0.71375 -0.32330 -0.64901 0.68867 If given a second argument, `svd' returns an economy-sized decomposition, eliminating the unnecessary rows or columns of U or V. File: octave, Node: Functions of a Matrix, Prev: Matrix Factorizations, Up: Linear Algebra Functions of a Matrix ===================== - Loadable Function: expm (A) Return the exponential of a matrix, defined as the infinite Taylor series expm(a) = I + a + a^2/2! + a^3/3! + ... The Taylor series is *not* the way to compute the matrix exponential; see Moler and Van Loan, `Nineteen Dubious Ways to Compute the Exponential of a Matrix', SIAM Review, 1978. This routine uses Ward's diagonal Pade' approximation method with three step preconditioning (SIAM Journal on Numerical Analysis, 1977). Diagonal Pade' approximations are rational polynomials of matrices -1 D (a) N (a) whose Taylor series matches the first `2q+1' terms of the Taylor series above; direct evaluation of the Taylor series (with the same preconditioning steps) may be desirable in lieu of the Pade' approximation when `Dq(a)' is ill-conditioned. - Loadable Function: logm (A) Compute the matrix logarithm of the square matrix A. Note that this is currently implemented in terms of an eigenvalue expansion and needs to be improved to be more robust. - Loadable Function: sqrtm (A) Compute the matrix square root of the square matrix A. Note that this is currently implemented in terms of an eigenvalue expansion and needs to be improved to be more robust. - Function File: kron (A, B) Form the kronecker product of two matrices, defined block by block as x = [a(i, j) b] For example, kron (1:4, ones (3, 1)) => 1 2 3 4 1 2 3 4 1 2 3 4 - Function File: [AA, BB, Q, Z] = qzhess (A, B) Compute the Hessenberg-triangular decomposition of the matrix pencil `(A, B)', returning `AA = Q * A * Z', `BB = Q * B * Z', with Q and Z orthogonal. For example, [aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8]) => aa = [ -3.02244, -4.41741; 0.92998, 0.69749 ] => bb = [ -8.60233, -9.99730; 0.00000, -0.23250 ] => q = [ -0.58124, -0.81373; -0.81373, 0.58124 ] => z = [ 1, 0; 0, 1 ] The Hessenberg-triangular decomposition is the first step in Moler and Stewart's QZ decomposition algorithm. Algorithm taken from Golub and Van Loan, `Matrix Computations, 2nd edition'. - Loadable Function: qzval (A, B) Compute generalized eigenvalues of the matrix pencil `A - lambda B'. The arguments A and B must be real matrices. - Loadable Function: X = syl (A, B, C) Solve the Sylvester equation A X + X B + C = 0 using standard LAPACK subroutines. For example, syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12]) => [ -0.50000, -0.66667; -0.66667, -0.50000 ] File: octave, Node: Nonlinear Equations, Next: Quadrature, Prev: Linear Algebra, Up: Top Nonlinear Equations ******************* Octave can solve sets of nonlinear equations of the form F (x) = 0 using the function `fsolve', which is based on the MINPACK subroutine `hybrd'. - Loadable Function: [X, INFO] = fsolve (FCN, X0) Given FCN, the name of a function of the form `f (X)' and an initial starting point X0, `fsolve' solves the set of equations such that `f(X) == 0'. - Loadable Function: fsolve_options (OPT, VAL) When called with two arguments, this function allows you set options parameters for the function `fsolve'. Given one argument, `fsolve_options' returns the value of the corresponding option. If no arguments are supplied, the names of all the available options and their current values are displayed. Here is a complete example. To solve the set of equations -2x^2 + 3xy + 4 sin(y) = 6 3x^2 - 2xy^2 + 3 cos(x) = -4 you first need to write a function to compute the value of the given function. For example: function y = f (x) y(1) = -2*x(1)^2 + 3*x(1)*x(2) + 4*sin(x(2)) - 6; y(2) = 3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4; endfunction Then, call `fsolve' with a specified initial condition to find the roots of the system of equations. For example, given the function `f' defined above, [x, info] = fsolve ("f", [1; 2]) results in the solution x = 0.57983 2.54621 info = 1 A value of `info = 1' indicates that the solution has converged. The function `perror' may be used to print English messages corresponding to the numeric error codes. For example, perror ("fsolve", 1) -| solution converged to requested tolerance File: octave, Node: Quadrature, Next: Differential Equations, Prev: Nonlinear Equations, Up: Top Quadrature ********** * Menu: * Functions of One Variable:: * Orthogonal Collocation:: File: octave, Node: Functions of One Variable, Next: Orthogonal Collocation, Prev: Quadrature, Up: Quadrature Functions of One Variable ========================= - Loadable Function: [V, IER, NFUN, ERR] = quad (F, A, B, TOL, SING) Integrate a nonlinear function of one variable using Quadpack. The first argument is the name of the function to call to compute the value of the integrand. It must have the form y = f (x) where Y and X are scalars. The second and third arguments are limits of integration. Either or both may be infinite. The optional argument TOL is a vector that specifies the desired accuracy of the result. The first element of the vector is the desired absolute tolerance, and the second element is the desired relative tolerance. To choose a relative test only, set the absolute tolerance to zero. To choose an absolute test only, set the relative tolerance to zero. The optional argument SING is a vector of values at which the integrand is known to be singular. The result of the integration is returned in V and IER contains an integer error code (0 indicates a successful integration). The value of NFUN indicates how many function evaluations were required, and ERR contains an estimate of the error in the solution. - Loadable Function: quad_options (OPT, VAL) When called with two arguments, this function allows you set options parameters for the function `quad'. Given one argument, `quad_options' returns the value of the corresponding option. If no arguments are supplied, the names of all the available options and their current values are displayed. Here is an example of using `quad' to integrate the function F(X) = X * sin (1/X) * sqrt (abs (1 - X)) from X = 0 to X = 3. This is a fairly difficult integration (plot the function over the range of integration to see why). The first step is to define the function: function y = f (x) y = x .* sin (1 ./ x) .* sqrt (abs (1 - x)); endfunction Note the use of the `dot' forms of the operators. This is not necessary for the call to `quad', but it makes it much easier to generate a set of points for plotting (because it makes it possible to call the function with a vector argument to produce a vector result). Then we simply call quad: [v, ier, nfun, err] = quad ("f", 0, 3) => 1.9819 => 1 => 5061 => 1.1522e-07 Although `quad' returns a nonzero value for IER, the result is reasonably accurate (to see why, examine what happens to the result if you move the lower bound to 0.1, then 0.01, then 0.001, etc.). File: octave, Node: Orthogonal Collocation, Prev: Functions of One Variable, Up: Quadrature Orthogonal Collocation ====================== - Loadable Function: [R, A, B, Q] = colloc (N, "left", "right") Compute derivative and integral weight matrices for orthogonal collocation using the subroutines given in J. Villadsen and M. L. Michelsen, `Solution of Differential Equation Models by Polynomial Approximation'. Here is an example of using `colloc' to generate weight matrices for solving the second order differential equation U' - ALPHA * U" = 0 with the boundary conditions U(0) = 0 and U(1) = 1. First, we can generate the weight matrices for N points (including the endpoints of the interval), and incorporate the boundary conditions in the right hand side (for a specific value of ALPHA). n = 7; alpha = 0.1; [r, a, b] = colloc (n-2, "left", "right"); at = a(2:n-1,2:n-1); bt = b(2:n-1,2:n-1); rhs = alpha * b(2:n-1,n) - a(2:n-1,n); Then the solution at the roots R is u = [ 0; (at - alpha * bt) \ rhs; 1] => [ 0.00; 0.004; 0.01 0.00; 0.12; 0.62; 1.00 ] File: octave, Node: Differential Equations, Next: Optimization, Prev: Quadrature, Up: Top Differential Equations ********************** Octave has two built-in functions for solving differential equations. Both are based on reliable ODE solvers written in Fortran. * Menu: * Ordinary Differential Equations:: * Differential-Algebraic Equations:: File: octave, Node: Ordinary Differential Equations, Next: Differential-Algebraic Equations, Prev: Differential Equations, Up: Differential Equations Ordinary Differential Equations =============================== The function `lsode' can be used Solve ODEs of the form dx -- = f (x, t) dt using Hindmarsh's ODE solver LSODE. - Loadable Function: lsode (FCN, X0, T, T_CRIT) Return a matrix of X as a function of T, given the initial state of the system X0. Each row in the result matrix corresponds to one of the elements in the vector T. The first element of T corresponds to the initial state X0, so that the first row of the output is X0. The first argument, FCN, is a string that names the function to call to compute the vector of right hand sides for the set of equations. It must have the form XDOT = f (X, T) where XDOT and X are vectors and T is a scalar. The fourth argument is optional, and may be used to specify a set of times that the ODE solver should not integrate past. It is useful for avoiding difficulties with singularities and points where there is a discontinuity in the derivative. Here is an example of solving a set of three differential equations using `lsode'. Given the function function xdot = f (x, t) xdot = zeros (3,1); xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) \ - 8.375e-06*x(1)^2); xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27; xdot(3) = 0.161*(x(1) - x(3)); endfunction and the initial condition `x0 = [ 4; 1.1; 4 ]', the set of equations can be integrated using the command t = linspace (0, 500, 1000); y = lsode ("f", x0, t); If you try this, you will see that the value of the result changes dramatically between T = 0 and 5, and again around T = 305. A more efficient set of output points might be t = [0, logspace (-1, log10(303), 150), \ logspace (log10(304), log10(500), 150)]; - Loadable Function: lsode_options (OPT, VAL) When called with two arguments, this function allows you set options parameters for the function `lsode'. Given one argument, `lsode_options' returns the value of the corresponding option. If no arguments are supplied, the names of all the available options and their current values are displayed. See Alan C. Hindmarsh, `ODEPACK, A Systematized Collection of ODE Solvers', in Scientific Computing, R. S. Stepleman, editor, (1983) for more information about the inner workings of `lsode'.